Configuration & CLI

This guide centralizes the runtime flags, .vyasa settings, and environment variables.

CLI

# Run on a directory (default port 5001)
vyasa .

# Custom host/port
vyasa . --host 0.0.0.0 --port 8000

# Disable auto-reload
vyasa . --no-reload

# Enable auth
vyasa . --user admin --password secret

# Build static site
vyasa build . -o ./dist

Configuration

Vyasa supports four ways to configure your blog (in priority order):

1. cli arguments (e.g. vyasa /path/to/markdown) - Highest priority
2. .vyasa configuration file (TOML format)
3. Environment variables - Fallback
4. Default values - Final fallback

Using a .vyasa Configuration File

Create a .vyasa file in your blog directory or current directory:

# Blog title (default: derives from root folder name via slug_to_title)
title = "My Awesome Blog"

# Root folder containing markdown files (default: current directory)
root = "."

# Server host (default: 127.0.0.1)
# Use "0.0.0.0" to make the server accessible from network
host = "127.0.0.1"

# Server port (default: 5001)
port = 5001

# Optional authentication credentials (enables Beforeware middleware)
username = "admin"
password = "hunter2"

# Optional: require auth for all routes (default: true if any auth provider is configured)
auth_required = true

# Optional Google OAuth configuration
[google_oauth]
client_id = "your-google-client-id"
client_secret = "your-google-client-secret"
allowed_domains = ["example.com"] # optional
allowed_emails = ["alice@example.com"] # optional

All settings in the .vyasa file are optional. The configuration is managed by the Config class in vyasa/config.py.

Layout Width Configuration

Set a single layout_max_width to control overall width (applies to both sidebar and non-sidebar pages). Values accept Tailwind max-width classes (e.g. max-w-7xl) or raw CSS sizes (e.g. 90vw, 1200px). Default is 75vw.

layout_max_width = "90vw"

Environment variable equivalent:

• VYASA_LAYOUT_MAX_WIDTH

Responsive behavior:

• At viewport widths below 1280px, layout containers are effectively full width.
• Between 1280px and ~1520px, the max width eases from 100% to your configured value to avoid a hard jump.
• Above that, the configured width is fully applied.

Custom Sidebar Ordering

Place a .vyasa file in any folder to control the sidebar order for that folder. .vyasa uses TOML format. Use order to pin items first, then sort and folders_first for the remainder.

# Items listed in order are shown first. Use exact names (include extensions).
order = ["todo.md", "static-build.md", "docs"]

# Sorting for items not listed in order
sort = "name_asc"          # name_asc, name_desc, mtime_asc, mtime_desc
folders_first = true
folders_always_first = false

Notes:

• folders_first only affects the items not listed in order.
• folders_always_first moves all folders to the top after ordering/sorting, while preserving their relative order.

Environment Variables

You can also use environment variables as a fallback:

• VYASA_ROOT: Path to your markdown files (default: current directory)
• VYASA_TITLE: Your blog's title (default: folder name converted via slug_to_title())
• VYASA_HOST: Server host (default: 127.0.0.1)
• VYASA_PORT: Server port (default: 5001)
• VYASA_USER: Optional username to enable session-based authentication
• VYASA_PASSWORD: Optional password paired with VYASA_USER
• VYASA_AUTH_REQUIRED: Require login for all routes (true/false)
• VYASA_GOOGLE_CLIENT_ID: Google OAuth client id (optional)
• VYASA_GOOGLE_CLIENT_SECRET: Google OAuth client secret (optional)
• VYASA_GOOGLE_ALLOWED_DOMAINS: Comma-separated allowed email domains (optional)
• VYASA_GOOGLE_ALLOWED_EMAILS: Comma-separated allowed emails (optional)

RBAC Configuration (optional)

Use rbac to protect specific paths by role. This is ignored unless an auth provider is enabled.

[rbac]
enabled = true
default_roles = ["reader"]
user_roles = { "alice@example.com" = ["admin"], "bob" = ["editor"] }
role_users = { "admin" = ["alice@example.com"], "editor" = ["bob"] }

[[rbac.rules]]
pattern = "^/admin"
roles = ["admin"]

[[rbac.rules]]
pattern = "^/private"
roles = ["admin", "editor"]

Environment variable (optional):

• VYASA_RBAC_ENABLED: Force enable/disable RBAC

Notes:

• If both user_roles and role_users are provided, roles are unioned at runtime.
• Google OAuth requires the optional dependency vyasa[auth].

Examples

Using a .vyasa file:

# Create a .vyasa file in your blog directory
title = "My Tech Blog"
port = 8000
host = "0.0.0.0"

Using environment variables:

export VYASA_ROOT=/path/to/your/markdown/files
export VYASA_TITLE="My Awesome Blog"
export VYASA_PORT=8000
export VYASA_HOST="0.0.0.0"
vyasa

Passing directory as argument:

vyasa /path/to/your/markdown/files

Enabling authentication:

# Via .vyasa file
title = "Private Blog"
username = "admin"
password = "secret123"
auth_required = true

[google_oauth]
client_id = "your-google-client-id"
client_secret = "your-google-client-secret"
allowed_domains = ["example.com"]

# Or via environment variables
export VYASA_USER="admin"
export VYASA_PASSWORD="secret123"
export VYASA_GOOGLE_CLIENT_ID="your-google-client-id"
export VYASA_GOOGLE_CLIENT_SECRET="your-google-client-secret"
export VYASA_GOOGLE_ALLOWED_DOMAINS="example.com"

Configuration priority example:

If you have both a .vyasa file with port = 8000 and an environment variable VYASA_PORT=9000, the .vyasa file takes precedence and port 8000 will be used.